Crate secret_service
source · [−]Expand description
Secret Service libary
This library implements a rust interface to the Secret Service API which is implemented in Linux.
About Secret Service API
http://standards.freedesktop.org/secret-service/
Secret Service provides a secure place to store secrets. Gnome keyring and KWallet implement the Secret Service API.
Basic Usage
use secret_service::SecretService;
use secret_service::EncryptionType;
use std::collections::HashMap;
// initialize secret service (dbus connection and encryption session)
let ss = SecretService::new(EncryptionType::Dh).unwrap();
// get default collection
let collection = ss.get_default_collection().unwrap();
let mut properties = HashMap::new();
properties.insert("test", "test_value");
//create new item
collection.create_item(
"test_label", // label
properties,
b"test_secret", //secret
false, // replace item with same attributes
"text/plain" // secret content type
).unwrap();
// search items by properties
let search_items = ss.search_items(
vec![("test", "test_value")]
).unwrap();
let item = search_items.get(0).unwrap();
// retrieve secret from item
let secret = item.get_secret().unwrap();
assert_eq!(secret, b"test_secret");
// delete item (deletes the dbus object, not the struct instance)
item.delete().unwrap()
Overview of this library:
Entry point
The entry point for this library is the SecretService
struct. A new instance of
SecretService
will initialize the dbus connection and negotiate an encryption session.
SecretService::new(EncryptionType::Plain).unwrap();
or
SecretService::new(EncryptionType::Dh).unwrap();
Once the SecretService struct is initialized, it can be used to navigate to a collection. Items can also be directly searched for without getting a collection first.
Collections and Items
The Secret Service API organizes secrets into collections, and holds each secret in an item.
Items consist of a label, attributes, and the secret. The most common way to find an item is a search by attributes.
While it’s possible to create new collections, most users will simply create items within the default collection.
Actions overview
The most common supported actions are create
, get
, search
, and delete
for
Collections
and Items
. For more specifics and exact method names, please see
each struct’s documentation.
In addition, set
and get
actions are available for secrets contained in an Item
.
Errors
This library provides a custom Error
. dbus
and rust-crypto
crate errors
are converted into Error
s.
Types of errors:
- dbus
- crypto
- parsing dbus output
- no result, if dbus gives back result but doesn’t contain expected parameter
- locked, if an object path is locked
- prompt dismissed, if action requires prompt but the prompt is dismissed
Crypto
Specifics in SecretService API Draft Proposal: http://standards.freedesktop.org/secret-service/
In this library, the encryption negotiation and key exchange is carried
out in the session
module, and encryption/decryption is done in the
ss_crypto
module.
Structs
Enums
Type Definitions
Result type often returned from methods that have Error.
Fns in this library return ::Result